home *** CD-ROM | disk | FTP | other *** search
/ IRIX Patches 1995 September / SGI IRIX Patches 1995 Sep.iso / relnotes / patchSG0000533 / ch2.z / ch2
Text File  |  1995-09-07  |  13KB  |  330 lines
  1.  
  2.  
  3.  
  4.                                   - 1 -
  5.  
  6.  
  7.  
  8.        2.  _D_M_A_P_I__I_m_p_l_e_m_e_n_t_a_t_i_o_n__N_o_t_e_s
  9.  
  10.        The following sections describe details of this
  11.        implementation that differ in some respect from the
  12.        Interface Specification.
  13.  
  14.        Note that this interface is newly created, still under
  15.        development, and not yet in use by released products as of
  16.        this writing.  While due effort and consideration will be
  17.        given to maintaining compatibility with this version in
  18.        subsequent releases, ccccoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy bbbbeeeettttwwwweeeeeeeennnn tttthhhhiiiissss rrrreeeelllleeeeaaaasssseeee aaaannnndddd
  19.        ffffuuuuttttuuuurrrreeee rrrreeeelllleeeeaaaasssseeeessss iiiissss nnnnooootttt gggguuuuaaaarrrraaaannnntttteeeeeeeedddd.  This applies both to the
  20.        basis for this implementation as described in the Interface
  21.        Specification and to the deviations in this particular
  22.        implementation as described here.
  23.  
  24.        2.1  _I_m_p_l_e_m_e_n_t_a_t_i_o_n__D_i_f_f_e_r_e_n_c_e_s
  25.  
  26.        This section describes features that have not been
  27.        implemented exactly according to their description in the
  28.        Interface Specification.
  29.  
  30.           +o The header file is <_s_y_s/_d_m_i._h>, not <_d_m_a_p_i._h>.
  31.  
  32.           +o Since multiple managed regions aren't supported in this
  33.             release, _d_m__s_e_t__e_v_e_n_t_l_i_s_t() allows one to set the _r_e_a_d,
  34.             _w_r_i_t_e, and _t_r_u_n_c_a_t_e events directly on a file.
  35.  
  36.           +o The _m_a_s_k argument is ignored in the _d_m__g_e_t__b_u_l_k_a_t_t_r(),
  37.             _d_m__g_e_t__f_i_l_e_a_t_t_r(), and _d_m__g_e_t__d_i_r_a_t_t_r_s() functions.
  38.             All information is returned for every call to any of
  39.             these functions.
  40.  
  41.           +o The _d_t__c_h_a_n_g_e field is not present in the _d_m__s_t_a_t
  42.             structure.
  43.  
  44.           +o The _b_u_f_l_e_n and _r_e_s_p_b_u_f_p fields are not present in the
  45.             _d_m__r_e_s_p_o_n_d__e_v_e_n_t() function.
  46.  
  47.           +o _d_m__w_r_i_t_e__i_n_v_i_s() does buffered, not synchronous writes.
  48.  
  49.           +o Asynchronous events are not sent when an operation
  50.             fails.  This applies to the _p_o_s_t_c_r_e_a_t_e, _p_o_s_t_r_e_m_o_v_e,
  51.             _p_o_s_t_r_e_n_a_m_e, _p_o_s_t_l_i_n_k, _p_o_s_t_s_y_m_l_i_n_k, _a_t_t_r_i_b_u_t_e, and
  52.             _d_e_s_t_r_o_y events.  These events should be used solely to
  53.             determine actual changes in the file system.
  54.  
  55.           +o There are no access rights.  Instead, the functions
  56.             _d_m__r_e_q_u_e_s_t__r_i_g_h_t(), _d_m__r_e_l_e_a_s_e__r_i_g_h_t(), and
  57.             _d_m__q_u_e_r_y__r_i_g_h_t() are replaced by _d_m__a_s_s_o_c__h_a_n_d_l_e(),
  58.             _d_m__d_i_s_a_s_s_o_c__h_a_n_d_l_e(), and _d_m__q_u_e_r_y__t_o_k_e_n()
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                   - 2 -
  71.  
  72.  
  73.  
  74.             respectively.  These replacement functions perform the
  75.             same task as the replaced versions with regards to
  76.             associating/disassociating a handle with a token.  The
  77.             sole difference is the absence of the access right
  78.             parameter, which controlled locking of the referenced
  79.             object.  In this implementation no locks are held on
  80.             any objects by a process sending an event.  Since a
  81.             process sending an event may be blocked for various
  82.             reasons (including waiting for the receiving DMAPI
  83.             application to reply to the event), the possibility of
  84.             a lock being held indefinitely is eliminated.  This
  85.             also eliminates the application's need to determine the
  86.             locking state of an object, and allows it to use the
  87.             interfaces freely without worrying about blocking due
  88.             to a lock it wasn't aware of.  The absence of locks
  89.             requires a different programming paradigm however.
  90.             Applications must enable and receive events on objects
  91.             that they wish to have exclusive access to.  For
  92.             example, to prevent access to a file's data, an
  93.             application would enable the _r_e_a_d, _w_r_i_t_e, and _t_r_u_n_c_a_t_e
  94.             events on the file, and not respond to any of them
  95.             until it was prepared to allow access to the file
  96.             again.
  97.  
  98.        2.2  _U_n_i_m_p_l_e_m_e_n_t_e_d__F_e_a_t_u_r_e_s
  99.  
  100.        This section contains a list of the items in the Interface
  101.        Specification that are not implemented in this release.
  102.        Items listed here are planned for inclusion in future
  103.        releases.
  104.  
  105.           +o The functions _d_m__g_e_t__m_o_u_n_t_i_n_f_o(), _d_m__g_e_t_a_l_l__d_i_s_p(), and
  106.             _d_m__m_o_v_e__e_v_e_n_t().
  107.  
  108.           +o All of the functions related to extended attributes:
  109.             _d_m__c_l_e_a_r__i_n_h_e_r_i_t(), _d_m__g_e_t__d_m_a_t_t_r(),
  110.             _d_m__g_e_t_a_l_l__d_m_a_t_t_r(), _d_m__g_e_t_a_l_l__i_n_h_e_r_i_t(),
  111.             _d_m__r_e_m_o_v_e__d_m_a_t_t_r(), _d_m__s_e_t__d_m_a_t_t_r(), and
  112.             _d_m__s_e_t__i_n_h_e_r_i_t().
  113.  
  114.        2.3  _A_d_d_i_t_i_o_n_s
  115.  
  116.        Additions not described in the Interface Specification are
  117.        contained here.
  118.  
  119.           +o The _d_t__i_g_e_n field has been added to the _d_m__s_t_a_t__t
  120.             structure.  It contains the inode generation number.
  121.  
  122.           +o A function of last resort, _o_p_e_n__b_y__h_a_n_d_l_e() has been
  123.             added.  Its prototype is:
  124.                  int open_by_handle (void *hanp, size_t hlen, int rw);
  125.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.                                   - 3 -
  136.  
  137.  
  138.  
  139.             The _r_w argument must be one of _O__R_D_O_N_L_Y or _O__R_D_W_R as in
  140.             the _o_f_l_a_g argument to _o_p_e_n(2), The return value is a
  141.             valid file descriptor or -1 on error.  I/O operations
  142.             done using a file descriptor obtained via
  143.             _o_p_e_n__b_y__h_a_n_d_l_e() will not update file access or change
  144.             times.  This function is provided as a workaround for
  145.             situations where the handle-based DMAPI interface is
  146.             discovered to be insufficient.  Any such situations
  147.             should be reported so that the necessary functionality
  148.             may be included in the interface.
  149.  
  150.        2.4  _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__L_i_m_i_t_a_t_i_o_n_s
  151.  
  152.        This section contains limitations that will be removed in
  153.        future releases.
  154.  
  155.           +o The _d_m__g_e_t__d_i_r_a_t_t_r_s() function will not return more
  156.             than 30k bytes of information no matter how large the
  157.             buffer supplied to it.
  158.  
  159.           +o The _d_m__g_e_t__e_v_e_n_t_s() function returns at most one event
  160.             per invocation.
  161.  
  162.           +o Only one managed region may be established per file.
  163.             This managed region must encompass the entire file.
  164.  
  165.           +o _d_m__p_u_n_c_h__h_o_l_e() requires the range freed to extend to
  166.             the end of the file.  _d_m__p_r_o_b_e__h_o_l_e() will properly
  167.             return an offset and length corresponding to this
  168.             limitation.  This restriction is a consequence of being
  169.             limited to one managed region.
  170.  
  171.           +o The offset and length given in the _r_e_a_d and _w_r_i_t_e
  172.             events are the values supplied to the file system, not
  173.             those representing the actual blocks the file system
  174.             may read or write in response.
  175.  
  176.           +o Attempting to unmount a file system that has the
  177.             _u_n_m_o_u_n_t event enabled will cause the unmount to block
  178.             uninterruptibly until the _u_n_m_o_u_n_t event is responded
  179.             to.  This means that attempting to shutdown the system
  180.             when there are mounted file systems with _u_n_m_o_u_n_t
  181.             enabled will cause the system to hang.  (The shutdown
  182.             process kills all user processes, including whatever
  183.             process may have handled _u_n_m_o_u_n_t events, leaving no one
  184.             to respond to _u_n_m_o_u_n_t events.)
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.                                   - 4 -
  202.  
  203.  
  204.  
  205.        2.5  _I_m_p_l_e_m_e_n_t_a_t_i_o_n_-_d_e_f_i_n_e_d__O_p_t_i_o_n_s
  206.  
  207.        This section describes implementation decisions made for
  208.        items listed in the Interface Specification as
  209.        "implementation defined".
  210.  
  211.           +o The _d_e_b_u_t event is not supported.
  212.  
  213.           +o Event messages are never dropped.  When a message can't
  214.             be queued immediately, the generating process is
  215.             blocked until it's interrupted or the message is
  216.             queued.  This applies to both synchronous and
  217.             asynchronous event messages.
  218.  
  219.           +o Processes blocked while attempting to queue an event
  220.             message on a session are interruptible if they are
  221.             blocked waiting for a session that is willing accept
  222.             the event message.  Processed blocked after queueing an
  223.             event message on a session and waiting for a response
  224.             are not interruptible.
  225.  
  226.           +o There is a limit of 2048 undelivered messages per
  227.             session.  Attempting to add more event messages to a
  228.             session that has reached the limit will cause the
  229.             process generating the event to block until previously
  230.             queued messages are delivered.
  231.  
  232.           +o Managed regions and event lists (enabled events) are
  233.             persistent.
  234.  
  235.           +o In all synchronous event messages using the
  236.             _d_m__n_a_m_e_s_p__e_v_e_n_t structure, the handle given in
  237.             _n_e__h_a_n_d_l_e_1 will be associated with the message's token.
  238.             Only one handle may be associated with each token.
  239.  
  240.        2.6  _A_d_d_i_t_i_o_n_a_l__I_n_f_o_r_m_a_t_i_o_n
  241.  
  242.        This section contains further explanation of features
  243.        implemented according to the Interface Specification, but
  244.        whose behavior was not specified fully.
  245.  
  246.           +o All DMAPI functions (except for _d_m__g_e_t__f_i_l_e_a_t_t_r)
  247.             require root permissions.
  248.  
  249.           +o The DMAPI is supported only on XFS file systems.  The
  250.             event generation feature of the DMAPI is enabled at
  251.             mount time by using the -_o _d_m_i option to _m_o_u_n_t(2).
  252.             This option must be specified for each file system.
  253.             File systems with existing DMAPI managed files that are
  254.             mounted without the -_o _d_m_i option are completely
  255.             accessible by all normal means and no events will be
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.                                   - 5 -
  268.  
  269.  
  270.  
  271.             generated.  This is normally extremely undesirable
  272.             because programs accessing files may read or write at
  273.             locations where data has been migrated.  However,
  274.             system administrators may find mounting without the -_o
  275.             _d_m_i option useful in recovering from a malfunctioning
  276.             DMAPI application.
  277.  
  278.           +o The DMAPI functions are in the _l_i_b_d_m._a library.  Use
  279.             the -_l_d_m compiler/linker option to access the library.
  280.  
  281.           +o For event messages using the _d_m__n_a_m_e_s_p__e_v_e_n_t structure,
  282.             the handle associated with the token is always handle 1
  283.             (i.e. the handle located by the _n_e__h_a_n_d_l_e_1 field of the
  284.             _d_m__n_a_m_e_s_p__e_v_e_n_t structure).
  285.  
  286.           +o On sending the _m_o_u_n_t event:  If there are no sessions
  287.             at the time a file system is mounted, or if all extant
  288.             sessions respond to the mount event with
  289.             _D_M__R_E_S_P__D_O_N_T_C_A_R_E, then the mount will proceed.  The
  290.             only case where a mount will fail due to the result of
  291.             delivering or attempting to deliver the _m_o_u_n_t event is
  292.             when an application responds to the _m_o_u_n_t event with
  293.             _D_M__R_E_S_P__A_B_O_R_T.
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.